 /*******************************************************************************
  * Copyright (c) 2004, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.ui.cheatsheets;

 import org.eclipse.swt.widgets.Composite;

 /**
  * Base class for adding controls to cheat sheet items.
  * <p>
  * Subclasses are used in conjunction with the
  * <code>org.eclipse.ui.cheatsheets.cheatSheetItemExtension</code> extension
  * point. Subclasses must be public and have a public 1-arg constructor
  * that takes the name of the attribute type <code>String</code>. The
  * extension point specifies the name of the subclass and the name of the XML
  * attribute that it can handle. When the cheat sheet framework encounters an
  * item (or subitem) element in the cheat sheet content file with an attribute
  * with a matching name, an instance of the corresponding item extension subclass
  * is created. It is up to this instance to remember the attribute value if
  * required. Later, when creating the visual controls for the item
  * are being created, the instance is given the opportunity to add extra controls.
  * </p>
  *
  * @since 3.0
  */
 public abstract class AbstractItemExtensionElement {
     
     /**
      * Name of the XML attribute that this item extension handles.
      */
     private String attributeName;
     
     /**
      * Creates a new item element extension for handling the
      * XML attributes of the given name.
      *
      * @param attributeName the name of the attribute that this item extension handles
      * @exception IllegalArgumentException if <code>attributeName</code>
      * is <code>null</code>
      */
     public AbstractItemExtensionElement(String attributeName) {
         if (attributeName == null) {
             throw new IllegalArgumentException ();
         }
         this.attributeName = attributeName;
     }

     /**
      * Returns the name of the XML attribute that this item extension handles.
      *
      * @return the name of the attribute that this item extension handles
      */
     public final String getAttributeName() {
         return this.attributeName;
     }
     
     /**
      * Called by the cheat sheet framework to parse and extract information
      * from the string value of the XML attribute.
      *
      * @param attributeValue the attribute value specified in the cheat sheet
      * content file
      */
     public abstract void handleAttribute(String attributeValue);

     /**
      * Called by the cheat sheet framework when creating the visual
      * representation of a step. This method should add a small button
      * (suggested size 16x16 pixels) to the given composite to decorate the step.
      * <p>
      * Important note: In some presentations of the cheatsheet, the color of the
      * background is varied to emphasize the current step. Because of this, it is
      * important to always use the background color of the composite
      * (<code>composite.getBackground()</code>) as the background color for any
      * additional controls; otherwise the new controls will not match their
      * surrounding.
      * </p>
      *
      * @param composite the composite to add extra controls to
      */
     public abstract void createControl(Composite composite);

     /**
      * Called by the cheat sheet framework to dispose of this item element extension.
      * <p>
      * This is the last method called on the <code>AbstractItemExtensionElement</code>.
      * At this point the controls (if they were ever created) have been disposed as part
      * of an SWT composite. There is no guarantee that createControl() has been called,
      * so the controls may never have been created.
      * </p>
      * <p>
      * Within this method an item element extension may release any resources, fonts,
      * images, etc.&nbsp; held by this part. It is also very important to deregister
      * all listeners.
      * </p>
      * <p>
      * Clients should not call this method (the cheat sheet framework calls this method
      * at appropriate times).
      * </p>
      */
     public abstract void dispose();
 }

